4.2 Software API and ROS

Kikobot C2 uses the same control architecture as C1: WebSocket on port 8080, motion planning and RViz from kikobot-backend c2, plus an optional camera stream on port 8081.

1. Starting the C2 stack

kikobot-backend c2

Mode	Command
Desktop + RViz	`kikobot-backend c2`
Headless	`export KIKOBOT_HEADLESS=1 && kikobot-backend c2`
systemd	`sudo systemctl start kikobot-backend@c2`

Environment:

Variable	Purpose
`KIKOBOT_C2_FIRMWARE_SCRIPT`	Override UART firmware path
`KIKOBOT_HEADLESS`	`1` = no RViz window
`ROS_DOMAIN_ID`	Default 0 if unset; must match other ROS tools

Default firmware: /opt/kikobot/share/c2/kikobot_uart_with_gripper_loop.py

On-disk API reference

Asset	Path
Markdown	`/opt/kikobot/share/doc/WEBSOCKET_INTEGRATION_GUIDE.md`
PDF	`/opt/kikobot/share/doc/WEBSOCKET_INTEGRATION_GUIDE.pdf`
Example client	`/opt/kikobot/share/examples/kikobot_ws_client_example.py`

2. WebSocket API (port 8080)

3.1 Connection

URL: ws://<robot-pc-ip>:8080
JSON messages; telemetry broadcast to all clients
No authentication — trusted LAN / VPN only

3.2 Handshake

{
  "type": "connected",
  "message": "Connected to Kikobot C2 WebSocket Bridge",
  "robot_profile": "c2",
  "capabilities": {
    "motion_planning_available": true,
    "arc_booklet_available": true,
    "hand_teaching_jog": true
  }
}

3.3 C2 bring-up from your application

(Admin) kikobot-backend c2
Connect WebSocket
{ "type": "firmware_status" }
{ "type": "start_firmware", "port": "/dev/ttyUSB0" }
Handle "joint_states" (~30 Hz)
{ "type": "home" } or { "type": "motion_plan", "waypoints": [...] }

Firmware control:

{ "type": "start_firmware", "port": "/dev/ttyUSB0" }
{ "type": "stop_firmware" }
{ "type": "firmware_status" }

port is optional when auto-detect works; must be a safe /dev/tty… path.

3. Command reference

`type`	Purpose
`home`	C2 home via firmware + planner sync
`jog`	Joint or Cartesian jog step
`hand_teaching`	Teach, save pose, gripper, firmware home
`motion_plan`	MoveJ / MoveL / Arc / Circle
`start_firmware` / `stop_firmware` / `firmware_status`	UART bridge
`save_motor_pose`	Read hardware joint positions
`fk_request`	Forward kinematics
`torque_release` / `torque_hold`	Torque off/on
`hand_teach_points_record`	Teach point recording toggle
`set_do` / `get_di`	Digital I/O
`start_waypoint_sequence`	Arc / booklet sequences
`run_program` / `stop_program`	Visual program runner

Jog

{
  "type": "jog",
  "axis": 0,
  "direction": 1,
  "mode": 0,
  "step": 1.0,
  "speed": 0.5
}

Hand teaching

{ "type": "hand_teaching", "command": [2.0, 0.0, 0.0] }

teach	save	Action
1	0	Teach on
0	1	Save pose
2	0	Open gripper
0	2	Close gripper
3	0	Home (firmware)

C2 home joints (degrees)

[92.53, 5.93, 102.73, 4.26, 90.07, 105.98]

4. Motion planning

{
  "type": "motion_plan",
  "waypoints": [
    {
      "goal_joint_angles": [92.53, 5.93, 102.73, 4.26, 90.07, 105.98],
      "goal_ee_pose": [],
      "motion_type": 0,
      "speed_fraction": 0.35,
      "sleep_time": 0
    },
    {
      "goal_joint_angles": [92.53, 5.93, 102.73, -13.22, 90.07, 105.98],
      "goal_ee_pose": [],
      "motion_type": 0,
      "speed_fraction": 0.35,
      "sleep_time": 0
    }
  ]
}

`motion_type`	Name	Waypoints per segment
0	MoveJ	2
1	MoveL	2 (TCP mm + deg)
2	Arc	3
3	Circle	3

Joint limits (deg): J1 ±165, J2 ±125, J3–J5 ±140, J6 ±175. Use margin below hard limits (e.g. J2 ≤ 124.95°).

Waypoint files: Keep goal joints within C2 planner limits. Do not reuse waypoint JSON from other robot models.

ROS CLI alternative (headless): With backend running and firmware up, move_joints.py in /opt/kikobot/share/c2/ can execute waypoint JSON on the same ROS domain — see HEADLESS_DOCKER_CLIENT_WORKFLOW.md.

5. Telemetry

`type`	Description
`joint_states`	`joint_names`, `angles` (deg), `angles_rad`
`jogging_feedback`	Active jog
`motion_planning_feedback`	Planner progress (`joint_angles` rad)
`status`	Command success/failure
`waypoint_sequence_status`, `arc_sequence_progress`	Booklet / arc automation

Example:

{
  "type": "joint_states",
  "joint_names": ["Revolute 1", "Revolute 2", "Revolute 3", "Revolute 4", "Revolute 5", "Revolute 6"],
  "angles": [92.53, 5.93, 102.73, 4.26, 90.07, 105.98],
  "angles_rad": [1.614, 0.103, 1.793, 0.074, 1.572, 1.849]
}

6. Camera & monitoring

Port	URL
8081	`http://<host>:8081/stream?topic=/camera/image_raw`

Kikobot Studio monitoring page expects this stream when a camera node is running in the backend launch graph.

7. Python reference client

pip install 'websockets>=12'
python3 /opt/kikobot/share/examples/kikobot_ws_client_example.py --host 127.0.0.1 status
python3 /opt/kikobot/share/examples/kikobot_ws_client_example.py --host 192.168.1.50 stream --seconds 10
python3 /opt/kikobot/share/examples/kikobot_ws_client_example.py --host 127.0.0.1 start-firmware --serial /dev/ttyUSB0
python3 /opt/kikobot/share/examples/kikobot_ws_client_example.py --host 127.0.0.1 demo-movej

The KikobotWebSocketClient class demonstrates concurrent handling of status replies and joint_states streams.

8. ROS 2 (advanced integrators)

Packages (prebuilt in `.deb`)

urdf_v3_description — C2 URDF / visualization
kikobot_motion_planner — trajectory planning and execution
custom_interfaces — motor pose and custom services

Topics & services (conceptual)

The UART firmware node subscribes to trajectory and hand-teaching traffic and publishes feedback used by the bridge. Exact topic names match the C2 launch configuration started by kikobot-backend c2.

Domain ID: Shipped backend uses ROS domain 0 when ROS_DOMAIN_ID is unset. Do not mix domain 33 in one shell and 0 in another.

Development / source tree (maintainers)

Workspace: Kikobot_C2_Software/
Dev launcher: start_c2_backend.sh
Operating guide: docs/1. Operating the C2 Full Stack.md

Customers on binary .deb installs do not need to compile ROS sources.

9. UART firmware capabilities

Script: kikobot_uart_with_gripper_loop.py

Trajectory execution from ROS
Hand teaching commands
Gripper and signal motor control
Home position
Port listing: --list-ports, -p /dev/ttyUSB0, --interactive

When started via WebSocket start_firmware, logs go to /tmp/kikobot_firmware.log.

10. Kikobot Studio features (C2)

Live 3D / RViz-backed visualization
Jog, hand teach, motion planning (MoveJ/L/Arc)
Monitoring page with camera
Waypoint sequences / industrial programming (feature flags per build)
Connects to the same 8080 API as external apps

11. Troubleshooting

Issue	Fix
No connection on 8080	`kikobot-backend c2` or `systemctl restart kikobot-backend@c2`
`context is invalid`	Restart backend
Motion server missing	`/tmp/kikobot_c2_display.log`, `kikobot-verify-backend`
Firmware exits	Wrong USB port, permissions, `/tmp/kikobot_firmware.log`
Joint limit errors	Clamp waypoints to C2 planner limits
`websockets` import error	`pip3 install --break-system-packages 'websockets>=12'`

ss -ltn | grep 8080
tail -f /tmp/kikobot_websocket.log

12. Security

Port 8080 binds on all interfaces without TLS or auth. Segment the robot network, use VPN, or tunnel via SSH.

[Installation and Integration](/docs/Kikobot C2/4.1 Installation and Integration)
[FAQ and Downloads](/docs/Kikobot C2/4.3 FAQ and Downloads)
[Kikobot C1 software and API](/docs/Kikobot C1/3.5 Software API and ROS) (shared protocol; different home pose & firmware)

1. Starting the C2 stack​

On-disk API reference​

2. WebSocket API (port 8080)​

3.1 Connection​

3.2 Handshake​

3.3 C2 bring-up from your application​

3. Command reference​

Jog​

Hand teaching​

C2 home joints (degrees)​

4. Motion planning​

5. Telemetry​

6. Camera & monitoring​

7. Python reference client​

8. ROS 2 (advanced integrators)​

Packages (prebuilt in .deb)​

Topics & services (conceptual)​

Development / source tree (maintainers)​

9. UART firmware capabilities​

10. Kikobot Studio features (C2)​

11. Troubleshooting​

12. Security​

13. Related documents​